Skunkware 5

home *** CD-ROM | disk | FTP | other *** search

/ Skunkware 5 / Skunkware 5.iso / lib / xephem / xephem.hlp < prev

Wrap

Text File | 1994-07-13 | 65KB | 1,331 lines

@Intro Xephem is a program that computes ephemerides for all the planets, some of their moons, plus any two user-defined objects. In addition to information in numeric form, xephem displays simple schematic views of Saturn, Jupiter, Mars, Luna and Earth as well as maps of the night sky and the solar system. The sky and solar system maps support labeling and trailing, and the solar system can be shown as a stereo pair. Xephem can compute information on demand or time can be set to increment automatically. In this way a series of computations and movies can be generated unattended. Quantitative information available about each object includes RA and Dec precessed to any epoch, local azimuth and altitude, heliocentric coordinates, distance from sun and earth, solar elongation, angular size, visual magnitude, illumination percentage, local rise, transit and set times, length of time up, constellation, and angular separations between all combinations of objects. Observing circumstance information includes UTC and local date and time, local sidereal time, times of astronomical twilight and length of night, local temperature, pressure and elevation above sea level for the refraction model and a monthly calendar. RA/Dec calculations are geocentric and may include the effects of light travel time, nutation, aberration and precession. Alt/Az and rise/set/transit and, optionally, angular separation calculations are topocentric and include the additional effects of parallax and refraction. Plot and listing files of selected field values may be generated as the program runs. The plot files are full precision floating point values in ASCII intended for export to other plotting programs. Xephem includes simple quick-look facilities to view plot files. The listing files are tables formatted for more general human reading. Xephem can read databases of objects. The objects may be fixed or specified via heliocentric elliptical, hyperbolic or parabolic orbital elements to accommodate solar system objects such as asteroids or comets. These are then available as candidate values for the user defined objects and all of them can be displayed in the sky map subject to type and magnitude filters. The format of the database file is described in the Help for the DB menu. @MainMenu Across the top of the Main menu is a menu bar to allow selecting the principle display menus of xephem. These may be turned on in any desired combination. Each menu will have its own Close button or it may be closed by reselecting it from the main menu bar. The "File" pulldown is a few miscellaneous controls. The "Reset" entry will return xephem to its initial state. The "Messages" entry toggles whether the general messages menu is displayed. Note that all messages that go to this menu also appear on stdout regardless of whether the menu is up. In order to be sure it is seen, the "messages" menu is always moved to the top of the window stack and placed under the pointer whenever it is up and new messages are added to it. The "Quit" entry exits xephem. The "View" pulldown toggles any of the several xephem displays. The "Control" pulldown toggles the plotting, listing and searching control menus. The "ObjX/Y..." pushbutton toggles the menu that allows you to define the user defined objects, ObjX and ObjY. Said menu also allows you to inspect each item currently in the xephem database. The "DB..." pushbutton toggles the menu that allows to add or replace entries in the xephem database from files of database objects. The "Preferences" pulldown lists the available preferences that may be changed at runtime. The options currently available include whether the algorithms are chosen for accuracy or speed; dates are shown and entered in month/day/year, year/month/day or day/month/year format; and whether local topocentric circumstances are given in English or Metric units of measure. Each of these may be initialized via the XEphem resources; see the sample XEphem.ad resource file for details. When the Algorithm setting is for Fast, a simpler precession algorithm is used and there is no correction for light travel time or nutation. Whenever the preferences are changed at run time, all effected fields are immediately recalculated. Finally, the "Help" pulldown provides access to several general areas of information. The next row is a status line that contains a short description of what xephem is doing at the moment with regards to its looping behavior. Below that is room for the NEW CIRCUMSTANCES message. When you change a field that would invalidate any of the other fields the message NEW CIRCUMSTANCES appears near the top of the menu. This will remain until at least one screen update loop occurs. See the Help for "Operation" for more information on changing the fields in the Main menu and controlling xephem's runtime behavior. See the Help for "Triad formats" for more information on these formats. Follows is a description of each of the display fields in the Main menu. UTC Date The UTC date. UTC Time The UTC time. Julian The current Julian date, to about 1-second accuracy. Sidereal The sidereal time for the current time and location.. TZ Name The local timezone name. The name field may be changed to any three-character mnemonic. TZ Offset Hours local time is behind UTC, ie, positive west or negative east of Greenwich. Local Date The local date. This is UTC minus the value of TZ Offset. Local Time The local time. This is UTC minus the value of TZ Offset. Twilight Dip The number of degrees the sun is below the horizon we wish to call twilight. This sets the value for the following fields. Dawn Local time when the sun center is "Twilight dip" degrees below the horizon before sunrise today. Dusk Local time when the sun center is "Twilight dip" degrees below the horizon after sunset today. Night Length Length of astronomical night, ie, Dawn - Dusk. If this and the display for Dawn and Dusk are shown as "-----", it means the sun is either always below or always above "Twilight dip" degrees below the horizon on this particular day. N Steps The number of times the display will be updated (time advanced by Step Size each step) automatically. Step Size The amount of time UTC (and its derivatives) is incremented each loop. Pause Number of seconds to pause between screen updates. This is used mainly to set up for free-running unattended operation. Pausing is not done when plotting or searching is on. Latitude Location latitude, positive degrees north of equator. Longitude Location longitude, positive degrees west of Greenwich meridian. Elevation Local elevation of the ground above sea level, in feet. (see implementation notes). Used in refraction correction. Temperature Local surface air temperature, in degrees F. Used in refraction correction. Atm Pressure Local surface air pressure, in inches of mercury. Used in refraction correction. Epoch The epoch, to the nearest 0.1 years, to which the ra/dec fields are precessed. This says (OfDate) when coordinates are not precessed, ie, are in the epoch of date. The calendar on the right of the Main menu is based on UTC. Selecting a date button will set the date. Unlabeled buttons before the first of the month and after the last of the month work as expected to also imply a change in month or year as necessary. The month and year buttons pop up selections that allow these to be changed as well. In no case does using the calendar change the current time (just the date). @Operation When xephem starts it sets the initial values of several fields from several X resource values. See the Help for "Initialization" for details of the format of these resources. Xephem then draws all fields on the Main screen with their initial values. The program then loops advancing time each step, by some amount you may control, and updating all fields each loop. There are three fields that control this looping behavior. "N Steps" controls the number of steps, "Step Size" the amount of time to add each step, and "Pause" is the amount of real seconds to pause between steps. When looping is in effect, the bottom button on the Main menu says "Stop". (Note that Xephem does not pause between steps when plotting or searching is on.) When the number of steps goes to 0 or the "Stop" button is selected, the looping stops and the button is relabeled "Update". Note that when looping with Pause set to 0, most numeric field data are not drawn in order to speed up the display. These values are always updated internally, however. and may safely be used for plotting, searching or listing. This is true even if the menu that displays the information is closed. Most fields may be changed by selecting them. A prompt dialog with a brief explanation of the field will be presented. A new value may be typed into the text field provided. If "Ok" is selected the new value will be used; if "Cancel" is selected the field will be left unchanged. In either case, the prompt dialog goes away. Some of the dialogs have an extra button as a handy way to enter frequently used values for the field. When you have changed a field that would invalidate any of the other fields the message NEW CIRCUMSTANCES appears near the top of the Main menu. This will remain until at least one screen update loop occurs. If you change any field that causes new circumstances, the "Step Size" value is not added to the current time after the first loop. Note also that after a series of loops, "N Steps" is automatically reset to 1 from 0 so "Update" will do exactly one loop again. @Credits First and foremost, I want to thank my lovely and loving wife, Kathy, for freely accepting me as I am and for encouraging and supporting my passion for astronomy in general and writing xephem in particular. Many formulas and tables are based, with permission, on material found in: "Astronomy with your Personal Computer" by Dr. Peter Duffett-Smith, Cambridge University Press, (c) 1985. Constellation algorithm is from a paper by Nancy G. Roman, "Identification of a constellation from a position", Publications of the Astronomical Society of the Pacific, Vol. 99, p. 695-699, July 1987. The high-precision precession routine is from 1989 Astronomical Almanac, as interpreted by Craig Counterman. Mr. Counterman also deserves the credit for providing the initial encouragement to write an astronomical tool specifically for X Windows. The Earth map is derived from one of the demos that comes with gnuplot, Copyright (C) 1986, 1987, 1990, 1991 Thomas Williams, Colin Kelley. The moon bitmap is derived from xphoon, Copyright (C) 1988 by Jef Poskanzer and Craig Leres. Jupiter's moons based on information in "Astronomical Formulae for Calculators" by Jean Meeus. Richmond, Va., U.S.A., Willmann-Bell, (c) 1982. Saturn's moons based on code supplied by Doug McDonald. Many test cases were gleaned from the pages of Sky and Telescope, (C) Sky Publishing Corp. I thank all the organizations behind the incredible Internet for its maintenance and free and easy access. National Space Science Data Center and the Institute for Theoretical Astronomy of the Russian Academy of Sciences for the asteroid database and the NSSDC and the Smithsonian Astrophysical Observatory for the SAO database. The members of the Saguaro Astronomy Club for the preparation and free distribution of their deep-sky database. Bright stars are from the Yale Bright Star catalog, as edited by Robert Tidd (inp@violet.berkeley.edu) and Alan Paeth (awpaeth@watcgl.waterloo.edu). Any errors in conversion to the ephem.db format are strictly mine. Special thanks to all the folks over the years who have provided innumerable ideas, suggestions and bug reports, both for xephem and its ancestor, ephem. A major benefit to writing and distributing these programs has been the chance to make friends from around the world. @Initialization Most of the fields in the Main xephem menu can be initialized from the X resources for class "XEphem". Of course, you may still change any field while the program is running too; these just set the initial conditions. Because of the way unspecified triad components are left unchanged (see help on Triad Formats) always specify all three for all such entries. For example, to initialize the longitude to zero degrees, say 0:0:0, not just 0. UD initial UTC date, such as 10/20/1988, or "Now" to use the computer clock. UT initial UTC time, such as 12:0:0, or "Now" to use the computer clock. JD time specified as a Julian Date. TZone hours the local time is behind utc, such as 5:0:0. You need not set this if you use "Now" for UT or UD. TZName name of the local time zone, such as CDT. 3 chars max. You need not set this if you use "Now" for UT or UD. This is purely a text label; xephem makes no attempt to compute anything from this label, such as a UTC offset. Long longitude, in degrees west of Greenwich, in the form d:m:s. Lat latitude, in degrees north of the equator, in the form d:m:s. Elevation height above sea level, in feet or meters, such as 800. Used to compute parallax of solar system objects. Temp air temperature, in degrees F or C, such as 60. Pressure air pressure, in inches of Mercury or mBar, such as 29.50. Temp and Pressure are used to compute refraction when the AdpHzrn option is active; see the Help for the Data setup table. StepSize the time increment between screen updates, such as "1" to give one hour updates. this can be a specific amount or RTC to use the system clock as a real-time source. You may also specify a time in days by appending a D (or d) after the number or a time in sidereal days by appending an s (or S) after the number. NSteps number of times program will loop automatically. see the discussion under Program Operation. Epoch this sets the desired ra/dec precession epoch. you can put any date here (use decimal form, such as 1992.5) or "EOD" to use the current instant ("Epoch of Date"). Pause The number of seconds to pause between calculation steps. TwilightDip Number of degrees the sun is below the horizon that you want to define as being the end of "twilight"; must be at least 0. @Date/time Xephem uses many values that get are entered in some variation of X/Y/Z form. We call this a "triad" input format. Times are displayed and entered in h:m:s format. If you pick a time field to change it. Any of the h, m, and s components that are not specified are left unchanged from their current value. For example, 0:5:0 set hours to 0, minutes to 5, seconds to 0, whereas :5 sets minutes to 5 but leaves hours and seconds unchanged. A negative time is indicated by a minus sign (-) anywhere before the first digit. Dates are displayed and entered in any one of month/day/year, year/month/day or day/month/year form. A preference selection on the main menu, and controlled by the XEphem resource DateFormat, selects which form is currently being used. As with time, components omitted when entering a new value retain the current value. For example, if the current date is 10/20/1988 and you type 20/30 the new date will become 20/30/1988. If you then type //2000 the new date will become 20/30/2000. Note you must type the full year since the program is accurate over several centuries either side of 1900. If you change the date, the time (ie, partial day) will not change. Negative years indicate BC dates. For example, Jan 1, 1 BC is given as 1/1/-1. There is no year 0. Two other ways to set the date are supported for compatibility with some published comet ephemerides. You may enter the day portion as a floating point number. When you set the day this way, the time will also change to correspond to the fractional portion of the day. You may also enter a date as a decimal year, as in 1990.12345. Also, when the date format preference is set to M/D/Y or D/M/Y the decimal point may be omitted if the value is not a reasonable month or date value, respectively. Decimal years are useful in interpreting plot files that include a date field, since date fields are stored in plot files as decimal years. Any input that includes exactly one decimal point is assumed to be a decimal year. Other parameters such as longitude, latitude and "Step Size" also fall into the general triad format. The same rules apply to these with respect to only having to set the portions that are being changed. As a matter of typing convenience, the program accepts most any punctuation character as the separator in a triad; you don't have to type a perfect ":" or "/". @Notes 1) The program uses a horizontal plane tangent to the earth Elev feet above sea level as the horizon for all altitude calculations, rise/set events, etc. Due to Earth's curvature, this is not the same as the angle up from the local horizon unless the observer is directly on the ground. The effect can be found from: sin(a)**2 = (h**2 + 2Rh) / (R+h)**2 where: R = radius of earth h = height above ground (same units as R) a = increase in altitude The effect can be significant. For example, the effect is more than two arc minutes at a height of 5 feet. 2) The accuracy of xephem can not be specifically stated since the Duffett- Smith book does not warrant its planet position polynomials to any given degree. I know for sure that better accuracy could be achieved if xephem used TDT but I have not yet decided on a suitable algorithm. Allowing for this manually, comparisons with the Astronomical Almanac are often within a very few arcseconds. 3) The sun-moon distance is the solution for the third side of a planar triangle whose two other sides are the earth-moon distance and earth-sun distance separated by the angle of elongation. 4) The calendar shows UTC, including dates of new and full moon. 5) The visual magnitudes for the planets take into account the phase of the illumination; the magnitudes for other solar system objects do not. 6) Ideas: + add tick marks (third axis?) to plots. + write a tool to find g/k from a set of predicted magnitudes. + search for occultations with all fixed objects. + add explicit searching for solar and lunar eclipses. + do more moons. + add a shorthand for synodic step sizes. + add e/w flip option to all displays. + use FileSelectionBox to choose plot, listing, and database files. + think of a way to display decimal years in plots as m/d/y. + incorporate Terrestrial Dynamical Time (known as Ephemeris Time prior to 1984). TDT is about 57 seconds ahead of UT1 in 1990. + account for lunar augmentation. + add undo for plot and listing selections. + use a progress meter during long operations, not just the watch cursor. + let xephem put things in the root window. + add lots more stuff to the Earth display, including interactive selection and tracking of lat/long and allow different viewpoints. + compute and display libration info in moon view. Bugs: - %0*.* in f_sexad() doesn't work on some systems (needs 0 deleted) - should jup moon +y be S??? - the built-in elements for pluto need to be updated. the elements for pluto in the included ephem.db database sampler are more accurate. - allow for decimal seconds in format converters. @Plot This menu controls the plot generation and display functionality of xephem. You may select most numeric information displayed by xephem, in pairs, to form x/y coordinates of a plot. You may select up to ten such pairs. You then select a file to contain the plot information. Xephem adds one line of information to the file for each x/y pair each time iteration step. Xephem can also plot any such file on the screen. The file format is compatible with the character version of xephem, ephem. Selecting data to plot: Select the "Select fields" toggle button to make each field in the other menus that are eligible for plotting appear as a pushbutton. Select each such button as desired to form the x or y component of a plot. As you make the selections, they are listed in the menu. You may also associate a one-character tag with each line. These tags will be included in the plot display for identification later. Once all the field choices have been made you may return all the menus to their normal operational appearance by reselecting the same toggle button. Specifying the plot file name: Type the name of the file to be used to contain the plot information in the text field provided. When xephem first needs to write to the file, it will first check for the existence of the file and, if it already exists, ask whether you wish to append to the file or overwrite it. The default plot file name may be specified as the value of the resource named "XEphem*Plot*Filename.value". If this resource is not specified then the file name will be "ephem.plt". Specifying a plot file title: Enter a short title for the plot information in the text are provided. When xephem first writes to a plot file, it will place the contents of the title text area, if it is not empty, into the file as a comment. All lines within a plot file that do not begin with an alphanumeric character are considered comments and are ignored. If the first line of a file is a comment, xephem will use it as the title for the plot when it displays the plot. Generating the plot entires: Once the fields have been specified and the plot file named and titled, you may select the "Plot to file" toggle button when ready. Now each time xephem goes through one iteration the values you have selected and their tags will be written to the plot file. Note that when plotting is activated, xephem does not update the screen until the "N Steps" count goes to 1. This greatly speeds the creation of plot files by avoiding screen updates. If you wish to watch each iteration, set "N Steps" to 1 and select the "Update" button manually for each iteration. Once all the desired data has been entered into the plot file, toggle the plot button back off to flush all data and close the file. The menus that contain each of the fields used in the plot need not be visible while the plot is being generated. Viewing plot files: Existing plot files may be viewed by entering their name into the text field provided and selecting the "Show plot file" pushbutton. As many different plot files may be viewed simultaneously as desired. Each plot has separate controls for flipping the X and Y axes and for turning on and off a reference coordinate grid. The xephem distribution kit includes a sample plot file of the analemma. @Listing This menu controls the list generation functionality of xephem. The fields you select define columns of a table written to a file as xephem runs. These columns look exactly like their corresponding fields on the xephem menus and so are more familiar and readable than the entries in plot files. They are designed to be used in further text processing operations or printed as-is. Two spaces are placed between each column. Selecting data to list: Select the "Select fields" toggle button to make each field in the other menus that are eligible for listing appear as a pushbutton. Select each such button as desired to form each column of the listing. As you make the selections, they are listed in the menu. Once all the column choices have been made you may return all the menus to their normal operational appearance by reselecting the same toggle button. Specifying the listing file: Type the name of the file to be used to contain the listing in the text field provided. When xephem first needs to write to the file, it will first check for the existence of the file and, if it exists, ask whether you wish to append to the file or overwrite it. The default listing file name may be specified as the value of the resource named "XEphem*List*Filename.value". If this resource is not specified then the file name will be "ephem.lst". Specifying a listing file title: All lines within a listing file that do not begin with an alphanumeric character are considered comments and are ignored. When xephem first writes to a listing file, it will place the contents of the title text area, if it is not empty, into the file as a comment for your convenience. Generating the listing entires: Once the fields have been specified and the listing file named and titled, if desired, select the "List to file" toggle button. Now each time xephem goes through one iteration the values you have selected will be written to the file. Note that when listing is activated, xephem does not update the screen until the "N Steps" count goes to 1. This greatly speeds the creation of listing files by avoiding screen updates. If you wish to watch each iteration, set "N Steps" to 1 and select the "Update" button manually for each iteration. Once all the desired data have been entered into the listing file, toggle the list button back off to flush all data and close the file. Menus that contain each of the fields used in the listing need not be visible for the fields to be listable. @Search This menu controls the automatic searching facility. You define an arithmetic or boolean function, using most of the fields xephem displays, then xephem will automatically evaluate the function and adjust the time on each iteration to search for the goal. To perform a search: enter a function, compile it, select a goal, set the desired accuracy, enable searching, start the search process. Each of these steps is described below. Entering the function: The function may be any arithmetic expression, in C-language syntax. All of C's comparison, logical and arithmetic operators are supported as well as several common arithmetic functions. Here is the complete list: + - * / && || > >= == != < <= abs sin cos tan asin acos atan degrad raddeg pi log log10 exp sqrt pow atan2 The function is entered into the text line provided. It may utilize most of the fields from the other xephem menus. Press the "Enable field buttons" button to make each available field a button. Where ever a field is desired in the function, position the text insertion cursor at the desired position and select the field; its name will be inserted into the function text. When you are finished defining the function, turn off the field button appearance by selecting the "Enable..." button again. Once you get to know the names of the fields you may also enter them manually, if you prefer. Compiling the function: Once the function has been entered as desired, it must be compiled by selecting the "Compile" button (or by pressing the Return or Enter key on your keyboard). If there are any errors, a diagnostic message will appear just below the function. Whenever a search function has been successfully compiled, the message will read <no compile errors>. Each time a function is successfully compiled, xephem updates all fields and evaluates the function. As explained below, this can be used as a sort of "astronomical calculator" even when not actually searching. Selecting a search goal: You may choose from any of three evaluation algorithms, as selected by the trio of radio buttons. "Find extreme" will search for a maxima or minima of the function. "Find 0" will search for a time when the function evaluates to zero. "Binary" will keep incrementing time by "Step Size" (in the main menu) until the state of the function changes, then do a binary search to find the exact time when the function changes state. Binary search interprets a function that evaluates to zero to be in one state and all other values to be the opposite state. Generally, binary functions are comprised of logical operators at their outermost expression levels. Specifying the desired accuracy: Searching will automatically stop when the time changes by less than the the accuracy value. Note that this method of detecting convergence is not based on the value of the search function itself. To change the desired accuracy press the pushbutton showing the current accuracy next to the "Accuracy" label and enter a new value in the dialog. Performing the search: Once the function is defined and it compiles without errors, you may enable searching by selecting the button at the top labeled "Searching is Active". Then, each time "Update" is selected on the main menu the search proceeds until either "N Steps" iterations have occurred or until "Step Size" becomes less than Accuracy. The initial search time and step size are set from the main menu, and are adjusted automatically as the search proceeds. Note that by setting "N Steps" to 1 and repeatedly selecting Update you can effectively single-step the search process. Search control will automatically turn off when convergence is detected, the function is edited or you may turn it off manually at any time by toggling the button labeled "Search is Active" back off. Additional notes on searching: When selecting fields for plotting or listing a button appears labeled "Use for plotting". You may select this button to use the evaluated search function as an item in the plot or listing feature. Note that the search function may be used in plotting and listing whether or not searching is enabled. The menus that contain each of the fields used in the search function need not be visible for the fields to used for searching. The "Close" button removes the search control menu from the screen; it does not effect actual search operation in any way. A successfully compiled search function is evaluated each time xephem updates. Whenever a search function is compiled it is also evaluated using freshly updated values. In this way, the Search menu can actually be used as an arbitrary "astronomical calculator" at any time. In each of these cases you need not be actually `searching' to use these feature. Hint: Searching periodic functions can lead to solutions far from the intended range. You will get best results if you can start the search near the expected answer and with a small step size that bounds the solution. You can use the plotting feature to study a function and get an idea of the solution, then use the automatic searching feature to zero in. @Data Table This is a table of information about each planet, Sol, Luna, and any two user defined objects, ObjX and ObjY. Each data item occupies one column in the table and each object occupies one row. Select the "Setup" button to configure the table rows and columns as desired. The initial configuration can be set from the X resources DataSelRows and DataSelMiscCols. See the sample XEphem.ad resource file for examples. When any columns related to rising or setting are active boxes at the bottom will indicate whether the Standard or Adaptive refraction model is in effect and whether the times refer to the center or the upper limb of the object. Similarly, when any of the separation columns are active a box will be present to indicate whether the separation is from a geocentric or topocentric point of view. See the help for the "Setup" menu for more information about these modes. Various odd ball rising, transit and setting conditions are accounted for and marked as follows when they occur: NoRise up some time but never rises, as such, today. NoSet up some time but never sets, as such, today. NoTran up some time but doesn't transit, as such, today. CirPol object is circumpolar (never goes below horizon) today. NvrUp object is never up today. XX:XX+ "+" appended to rise, transit or set times means the event occurs twice today; the time given is the time of the first event. "+" appended to "Hours Up" means it is still up at midnight. Any of the information in this table may be plotted, listed or used in a search algorithm. See the help for these control functions for more details. See the help for the "Setup" menu for a description of each field. @DataSelection Table This menu lets you configure which rows and columns will be in the Data Table. When this menu first comes up it will be set to indicate the state of the Data Table. You may then manipulate the toggle buttons as desired. To actually change the Data Table to a new configuration select the "Apply" button. "Ok" does the same thing but also closes this menu. "Close" just closes this menu without making any permanent changes. In addition to manipulating each item individually, each columns includes handy shortcut controls at the top to make changes to column as a whole. The first column of this menu selects which rows will be present in the Data Table. The planets and the sun and moon are always in this column. If user defined objects ObjX or ObjY are defined then they will also be present and controllable from this column. See the help for the "ObjX/Y" menu for more information about user defined objects. Entries in the remaining three columns in this menu control which columns will be present in the Data Table. They are grouped into three categories for convenience. Column two controls miscellaneous basic information. The descriptions of each entry are as follows: Cns name of the constellation in which the object appears. R_A apparent geocentric right ascension of object, precessed to given epoch, in hours, minutes and decimal minutes. Dec apparent geocentric declination of object, precessed to given epoch, in degrees and minutes. Az degrees eastward of true north for object. Alt degrees up from a horizontal plane that is Elevation feet above sea level. HeLong true heliocentric longitude, in degrees. Earth's is displayed on the sun's line. For the moon this is the geocentric longitude. HeLat true heliocentric latitude, in degrees. For the moon this is the geocentric latitude. EaDst true distance from Earth center to object center, in AU, except distance to the moon is in miles or km depending on the Units preference. SnDst true distance from sun center to object center, in AU. Elong spherical angular separation between sun and given object, calculated from the their geocentric ecliptic coordinates. Note this is not just the difference in ecliptic longitude. The sign, however, is simply sign(obj's longitude - sun's longitude), ie, degrees east. thus, a positive elongation means the object rises after the sun. This field is not generally useful in searching for conjunctions because of the discontinuous sign change that occurs at conjunction. Size angular size of object, in arc seconds. VMag visual magnitude of object. Phase percent of visible surface in sunlight. Note the moon phase is calculated simplistically as just abs(elongation)/180*100 which can be a few degrees off... this means that because of how elongation is defined it doesn't say 0 during new moon (or 100 during full) except during close eclipses (maybe that's a "feature"?). Column three controls information related to rising, transiting, and setting. These may be computed according to two options. "StdRefr", which stands for "standard refraction", computes rising and setting based on the standard horizon refraction of 32 arc minutes. This agrees well will standard publications. "AdpRefr", which stands for "adaptive refraction", computes rising and setting based on a refraction model that used the actual atmospheric and topocentric circumstances displayed on the Main menu. This generally leads to accuracies well within one minute if all conditions are carefully entered. "Limb" means that the rise and set circumstances are based on the location of the upper limb of the object. "Center" means that the circumstances are based on the location of the center of the object. (In fact, these allowances are only taken into account for the Sun and moon.) Follows is a description of the Data Table columns controlled by the third Data Selection column: RiseTm RiseAz The local time and azimuth when the upper limb (or center) of the object rises today. TrnTm TrnAlt The local time and altitude when the object crosses the meridian today, ie, when its azimuth is true south or, if no precession, when the local sidereal time equals the object's right ascension. SetTm SetAz The local time and azimuth when the upper limb (or center) of the object sets today. HrsUp The number of hours the object is up today, that is, the difference between the set and rise times. Note that these times are for the current local day. See the description of "odd ball" circumstances that this definition can produce and how xephem reports them. The last column in the Data Table setup menu controls for which objects angular separation is computed. Each entry in the Data Table will be the angular separations between each pair of objects, in degrees. The vantage point for the Separation values may be chosen. "Geocentric" ignores local conditions and gives the separation as seen from Earth center. "Topocentric" uses the local conditions known to xephem. The choice is particularly critical for lunar occultations, but the effect can be significant for the planets. Geocentric separations between objects and the sun will match the magnitude of the elongation given in the Data menu. When ObjX or ObjY are defined, these will appear in the last column and separations between them and the other objects (in column 1) may be selected for display. Note: Searching over a period that will include the rise or set times of either object is generally better performed from the geocentric viewpoint. The refraction effect of the topocentric viewpoint causes many arcminutes of rapid whiplash displacement as the objects rise and set that overlays the smooth celestial motion of the objects. This rapid position variation can confuse the solver algorithms that expect fairly smooth functions. @Mars This menu displays the central meridian longitude of Mars, that is, the Martian meridian currently facing towards Earth. This value may be selected for plotting, listing and searching as described in the help for these functions. Also included in this menu is a simple schematic display of the Martian surface at the current time. I would like to find a map with a bit more detail. @Earth This menu displays a simple map of the Earth oriented so that the subsolar point is centered. The subsolar point is the location on the Earth from which the sun appears to be directly overhead. Another way to interpret the display is to think of it as displaying exactly that portion of the Earth currently in sunlight. The subsolar point is marked with a cross. The latitude and longitude of the current subsolar point are displayed and may be selected for plotting, listing or searching as described in the help for those functions. It is interesting to set the step size to a few integral number of days and watch the change in latitude. Plotting latitude vs. longitude over the course of a year is equivalent to plotting the analemma. Remember that the numeric information is not updated while looping with Pause set to 0. @Sky View This menu displays each object currently loaded in the xephem database with several display options, subject to filtering by type and magnitude range. The central display is intended to be similar to a telescopic view. Descriptions of each function are keyed to the schematic depiction below: _____________________________________________ |Alt-Az | | [Alt] [Az] | | |RA-Dec | F | | A | |--------| O | | l | |Grid | V | | t | |--------| | | | |F Mag | | | / | |B Mag | | Sky | | |--------| | | D | |Dots | | | e | |Ecliptic| | | c | |Labels | | | | |--------| | | | |Locate | | | | |--------| | [RA] [Dec] | | | |___|__________________________|___| | | Az / RA | | |__________________________________| | | Date/Time stamp | |________|__________________________________| | Filter Close Help | |___________________________________________| Alt-Az / RA-Dec The radio box in the upper left corner selects whether the display coordinate system is Altitude-Azimuth or Right Ascension-Declination. Whenever the Alt-Az system is used, nothing is displayed that would lie below the current horizon (except trails; see note under Sky). The orientation of the display circle is always without reflections. In Alt-Az mode, left, right, up and down as are they would appear to the otherwise unaided eye. In RA-Dec mode, up is always celestial north, left is always celestial East. The meridian named by the horizontal slider is always the line between the center of the field-of-view and the nearest pole. Grid The toggle button labeled "Grid" controls whether a calibration grid will overlay the display. When the grid is displayed, its graduation is displayed below the toggle button. F Mag / B Mag The two sliders on the left set the brightness range being displayed. Only objects that are currently within the selected range will be shown on the display. Note that sliding either scale beyond its opposite is not permitted but it is permitted to do this by selecting in the slider trough should you really want to do this (to turn off all objects). Note this does not effect trails. Dots The toggle on the left labeled "Just Dots" selects how objects are drawn. When the toggle is pushed in, objects of all types are displayed simply as dots. The diameter of the dots equals the difference between its magnitude and the faintest magnitude. In this way the size of the dots can be changed as desired. When the toggle is released, each type of object is displayed with a unique schematic symbol. These symbols may be viewed from the Filter menu. In this case too the size is proportional to magnitude above the faintest limit. In either form, the color of the object is displayed according to the value established for each basic type in the X resource database. See the sample XEphem.ad resource file for examples of setting object colors. Ecliptic The toggle on the left labeled "Ecliptic" selects whether a dotted line is drawn along the ecliptic. The ecliptic is the plane of the Earth's orbit or, as seen from Earth, the path of the Sun and the approximate path of the planets across the sky. Labels The toggle on the left labeled "All labels" controls whether the labels for all objects are forced on. This does not effect which objects have their individual "Persistent label" options on. Locate The button labeled "Locate..." will pop up a list of the basic objects and the defined user defined objects, if any. Selecting any of these entries will place a cross-hair over the object. If the object is not within the field of view the object will first be centered, unless Alt-Az mode is currently active and the object is below the horizon. To locate other objects use the ObjX/Y menu. FOV The left vertically-oriented slider controls the field-of-view of the display circle. This can be varied from 1 to 180 degrees. [Alt] [Az] [RA] [Dec] The coordinates of the cursor are tracked and displayed across the bottom and top of the circular display area as long as it is within the circle and the left mouse button is depressed. NOTE: The values displayed during tracking for the coordinate system opposite to the one currently in effect may not agree exactly with the values displayed elsewhere by xephem, particularly for close solar system objects. To understand why recall that in all these other displays xephem computes geocentric RA/Dec and topocentric Alt/Az. Recall further that parallax contributes significantly to the difference between these points of view and parallax depends on the distance to each particular object. Thus, there is no single transformation between these coordinate systems that is correct for all objects. During tracking, the transformation to the coordinate system opposite to the one in current use by the Sky View display is computed without regard to parallax; this is strictly correct only for objects very far away. This has the useful result that while in RA/Dec coordinate mode the tracking values for Alt/Az may be thought of as being geocentric; and while in Alt/Az mode, RA/Dec will be topocentric. Sky The center circular area is the sky display of objects. Follows is a description of the operations that may be performed in this area using the pointer. If the pointer is placed near a visible object and the third button is pushed, a popup will appear. This will present several basic data for the object. This data is exactly the same as that which is available in the Data Table menu; see it's Help for more information. If a trailed object is selected, the data will be as it was at the time the position was created. In addition, the popup offers several control operations, as follows: Selecting "Point" from the popup will center the object in the field of view (as well as can be done with the accuracy of the pointing scales anyway). Selecting "Make ObjX/Y" will assign the given object to become ObjX or ObjY, depending on which one is currently being displayed in the ObjX/Y menu. See the help for the ObjX/Y menu for more information on that menu. Selecting "Leave Trail" will start to accumulate all positions of the given object as time is advanced. Each new location will be connected with a line to its previous location. The trails remain correct if the display coordinate system is changed. Trails may be turned on or off without loss of trail information. However, trailing information is discarded if trailing is turned off when a new time step is performed. If any point in a trail is selected the information displayed is as per the object at that time. The fastest way to accumulate trailing information is to turn trailing on and pop the menu down while running. Note that in Alt-Az mode, if an object goes below the horizon the line segments of the trail are displayed but not the actual points. Selecting "Persistent Label" will place the name of the object near it on the display. This will remain until the label is turned off. Note this option is maintained separately for trailed objects and for the untrailed objects; that is, you have independent control over labeling for a trailed object and its currently displayed object since the latter also always appears in the trailed list. The coordinates of the cursor are displayed in the corners of the circular sky area as long as the cursor is within the central circle and the left mouse button is depressed. Alt / Dec The right vertically-oriented slider controls one of two axes that defines the direction in which the display points. In Alt-Az mode this controls altitude and can be varied from 0 to 90 degrees. In RA-Dec mode this controls Declination and can be varied from -90 to +90. Az / RA The bottom horizontally-oriented slider controls one of two axes that defines the direction in which the display points. In Alt-Az mode this controls azimuth and can be varied from 0 to 359 degrees. Azimuth 0 is north and increases eastward. In RA-Dec mode this controls Right Ascension and can be varied from 0 to 23.9 hours. Date/Time Stamp This displays the date and time for which the display is valid. Filter The Filter button along the bottom brings up a menu that controls whether classes of objects are displayed. Using the Filter menu, one may select which classes of objects are desired. Selecting "Apply" updates the sky display according to the desired selection. Selecting "Ok" does the same thing but also closes the filter menu. For reference, the Filter menu also contains the schematic symbol for each type of object, and its code when used in a database file. @Solar System View This is a graphical representation of the solar system. The Sun is always at the center of the screen, marked as a plus (+). The three sliders at the edges control the position of the observer. The vertical slider on the left controls the distance from the sun -- you are closer as the slider is slid further up. The horizontal slider under the view controls the heliocentric longitude -- think of it as a rotation about the central axis. The vertical slider on the right controls the heliocentric latitude -- your angle above the ecliptic plane. Any feature may be identified by pointing near it and clicking the right mouse button. This will bring down a temporary popup menu with additional information until the button is released. The RA/Dec given for the Earth is that of the sun. All RA/Dec info displayed is for the epoch as it was set on the Main menu when the dot was computed. The "Leave trails" option can be used to retain old dots. By turning on the "Connect dots" option, these dots are connected by line segments. The fastest way to accumulate lengthy trail operation is to turn on trailing and run with the menu popped down. The planets may be individually turned on and off, without loss of any display data associated with them, by using the toggle panel near the bottom. If ObjX or ObjY are defined and are solar system objects then they will appear on the display and in the list. The bottom button marked "Stereo" is used to bring up another image of the solar system from a slightly displaced vantage point. Adjusting your gaze to fuse the two images together will reveal a 3D image. This effect is most pronounced if trails have been turned for a significant portion of the orbits of the objects of interest. This effect was designed primarily to help visual the orbits of comets. At the bottom of the stereo display is a slider to control the location of the second vantage point. When the slider is in the center both views are identical. Moving the slider to the left will display the scene as though the viewer has moved such as to move the objects to the left. Objects closer to the viewer move more. Moving the slider to the right does the same but in the opposite direction. In this way, you may adjust the stereo effect to be most comfortable to you, and with or without requiring crossed eyes. Closing the main Solar System menu will close both it and the Stereo menu, If the Solar System menu is closed while the Stereo menu is on, it will reappear when the Solar System menu is reactivated. if it is up. @DataBase menu This menu allows you to inspect and modify the collection of objects that are currently in memory. These objects form what is referred to as the xephem database. The top portion of the menu displays a count of each major type of object in the database. Xephem supports files that contain descriptions of objects. These files may be read into memory either adding to the current database or replacing it. Enter the name of the desired xephem database file in the text area provided then select either "Append" or "Replace", respectively. The default database filename may be specified by setting the X resource named "XEphem*DBPromptD.textString". The internal default name is "ephem.db". The xephem distribution kit includes a sample ephem.db that contains more than 15,000 objects of all types. Also available from the author is the entire Smithsonian Astrophysical Observatory star list. These have been sorted into ten sky regions. There is one file per region. The entire set is some 11MB. Follows is a description of the format of these database files. This format remains compatible with the "ephem" dumb-terminal version of xephem for those interested. Note that the "Filter" menu accessible from the "Sky View" menu also includes a list of the type codes for each object, for easy reference. Each object occupies one line. Fields are separated with commas. Some fields are further subdivided into subfields with vertical bars (|). Lines beginning with anything other than a-z, A-Z or 0-9 are ignored and may be used for comets. Objects may be in any order. Where they appear, all date fields may be in either of two forms: 1) month/day/year, where day may contain a trailing decimal portion. examples: 1/1/1993 and 1/1.234/1993 NOTE: this is always the format of dates in database files, regardless of the current xephem run-time Data format preference setting. 2) a real-number, such as 1993.123. The first two fields are always Name and Type. Remaining fields depend on the form of the object's motion. The Name field is the object's name. The Type field always starts with a single letter designating the form of the object's motion: f: fixed (no proper motion) e: heliocentric elliptical orbit h: heliocentric hyperbolic orbit p: heliocentric parabolic orbit if "Type" is fixed, an object class code may follow in the next subfield: C: Cluster, globular U: Cluster, with nebulosity O: Cluster, open G: Galaxy, spiral H: Galaxy, spherical A: Cluster of galaxies N: Nebula, bright F: Nebula, diffuse K: Nebula, dark P: Nebula, planetary Q: Quasar T: stellar object B: Star, binary D: Star, double M: Star, multiple S: Star V: Star, variable if class is one of T, B, D, S or V, the spectral class and possibly the numerical subclass designation may follow in the next subfield: O, B, A, F, G, K, M, N, C, S For other object types, the remaining fields are defined as follows: elliptical format (e < 1): i = inclination, degrees O = longitude of ascending node, degrees o = argument of perihelion, degrees a = mean distance (aka semi-major axis), AU n = mean daily motion, degrees per day (computed from a**3/2 if omitted) e = eccentricity, M = mean anomaly (ie, degrees from perihelion), E = epoch date (ie, time of M), D = the equinox year (ie, time of i/O/o). g/k or H/G = magnitude model; select which by preceding the first field with either a "g" or an "H"; H/G is the default if neither is given. s = angular size at 1 AU, arc seconds, optional hyperbolic format (e > 1): T = epoch of perihelion i = inclination, degrees O = longitude of ascending node, degrees o = argument of perihelion, degrees e = eccentricity, q = perihelion distance, AU D = the equinox year (ie, time of i/O/o). g/k = magnitude model s = angular size at 1 AU, arc seconds, optional parabolic format (e == 1): T = epoch of perihelion i = inclination, degrees o = argument of perihelion, degrees q = perihelion distance, AU O = longitude of ascending node, degrees D = the equinox year (ie, time of i/O/o). g/k = magnitude model s = angular size at 1 AU, arc seconds, optional fixed format: RA, hours Declination, degrees magnitude reference epoch s = angular size, arc minutes, optional @Object Xephem supports two user-defined objects, denoted ObjX and ObjY. These may be fixed objects or objects in elliptical, hyperbolic or parabolic heliocentric orbits. The ObjX/Y dialog allows you to define these objects. Xephem maintains a working copy of these objects for use with the ObjX/Y menu that is separate from the real ObjX and ObjY. The ObjX/Y menu always works on these working copies. The working copies and the real ObjX/Y only interact when using the Ok, Apply and Reset control, as described shortly. The ObjX/Y menu is always displaying information from one or the other of these working copies as indicated by the small radio box in the center of the menu at the top. This box may also be used to changed whether ObjX or ObjY is being displayed and manipulated. We will refer to the one selected as the "current working object." The radio box in the upper left displays the basic type of the current working object. This can be changed by selecting another of the collection of toggle buttons. In the left and center of the menu is an area that lists each field for the current working object and its present value. The list is adjusted to correspond to the fields that are associated with the type of the current working object. These fields may be changed by selecting the button that contains their value. This will bring up a small text entry dialog. A new entry may be typed into the dialog box and applied by hitting RETURN or selecting the "Ok" button. The value may be left unchanged by selecting "Cancel". Along the right edge of the ObjX/Y menu is a list of each object currently loaded into the xephem database. (See the Help for the "Data Base" menu for more information on manipulating this data base.) If there are more than 20 items then a scroll bar may be used to browse through the list. The entries are sorted in numeric and alphabetic order for easy selection. If one of these objects is selected, then it is copied to the current working object. You may then further edit the values for this working object as desired. When the current working object is as you want it, select "Apply" to copy it the real ObjX (or ObjY) used throughout the other functions of xephem. "Ok" will do the same thing and also close the ObjX/Y menu. Selecting "Reset" will load the current working object with a copy of the real ObjX (or ObjY). Selecting "Sky Point" will move the center of the field of view on the "Sky View" menu so that the current working object is centered and a cross-hair is drawn over the object. This change in pointing direction and marking will take place even if the object is not in the Sky View type filter or within the magnitude range. Note that the Sky View display will _not_ be changed if it is set to Alt-Az mode and the current working object is below the horizon. Selecting "Sky Mark" will draw a cross-hair on the Sky View menu at the location of the current working object if it is within the Sky View field of view. The Sky View menu is never reaimed with this command. Follows is a description of each field for the type of the current working object. To get a description of the fields for other types of objects, change the type of the current working object and reselect Help. @Fixed Object +Object Fixed objects are characterized by five parameters: RA, Dec, magnitude, the reference epoch for the coordinates and angular size in arc seconds, optional Note: In order to conserve memory usage, xephem stores the RA and Dec for a fixed object only once with each object. These values are always precessed _in place_ to the current display epoch. Thus, you will find that the RA and Dec displayed for a given object may change if the epoch is changed on the main menu and the object information is redisplayed here on the ObjX/Y menu. @Elliptical Object +Object Elliptical objects are characterized by 12 parameters: the parameters that define a heliocentric elliptic orbit and the coefficients for either of two magnitude models. These elements are the same ones often listed in the Astronomical Almanac. The elements are, in order: i = inclination, degrees O = longitude of ascending node, degrees o = argument of perihelion, degrees a = mean distance (aka semi-major axis), AU n = mean daily motion, degrees per day e = eccentricity M = mean anomaly (ie, degrees from perihelion) E = epoch date (ie, time of M) D = the equinox year (ie, time of i/O/o) g/k or H/G = either of two magnitude models; see below s = angular size at 1 AU, arc seconds, optional You might have other parameters available that can be converted into these. The following relationships might be useful: P = sqrt(a*a*a) p = O + o n = 0.9856076686/P T = E - M/n q = a*(1-e) AU = 149,597,870 km = 92,955,621 U.S. statute miles where P = the orbital period, years; p = longitude of perihelion, degrees T = epoch of perihelion (add multiples of P for desired range) q = perihelion distance, AU Note that if you know T you can then set E = T and M = 0. Xephem supports two different magnitude models for elliptical objects. One, denoted here as g/k, is generally used for comets in elliptical objects. The other, denoted H/G, is generally used for asteroids in the Astronomical Almanac. +OBJXY_gkMAGNITUDE When using this model for elliptical objects, the first of the two magnitude fields must be preceded by a letter "g". This applies in both the ephem.db database file and the corresponding menu elliptical object definition prompt; otherwise the default magnitude model for elliptical objects is the H/G model. +OBJXY_HGMAGNITUDE The H/G model is the default magnitude model for elliptical objects but it can also be explicitly indicated when the first of the two magnitude fields is preceded by a letter "H". This works in both the ephem.db database file and the corresponding menu elliptical object definition prompt. @Hyperbolic Object +Object Hyperbolic objects are characterized by 10 parameters: the parameters that define a heliocentric hyperbolic orbit and the magnitude model coefficients. These orbital parameters are, in order: T = epoch of perihelion i = inclination, degrees O = longitude of ascending node, degrees o = argument of perihelion, degrees e = eccentricity, q = perihelion distance, AU D = the equinox year (ie, time of i/O/o). g/k = magnitude model s = angular size at 1 AU, arc seconds, optional As with elliptical elements, other parameters might be available. The relationships are generally the same, except for: q = a*(e-1) +OBJXY_gkMAGNITUDE @Parabolic Object +Object Parabolic objects are characterized by 9 parameters: the parameters that define a heliocentric parabolic orbit and the magnitude model coefficients. These orbital parameters are, in order: T = epoch of perihelion i = inclination, degrees o = argument of perihelion, degrees q = perihelion distance, AU O = longitude of ascending node, degrees D = the equinox year (ie, time of i/O/o). g/k = magnitude model s = angular size at 1 AU, arc seconds, optional +OBJXY_gkMAGNITUDE @OBJXY_gkMAGNITUDE The g/k magnitude model requires two parameters to be specified. One, the absolute magnitude, g, is the visual magnitude of the object if it were one AU from both the sun and the earth. The other, the luminosity index, k, characterizes the brightness change of the object as a function of its distance from the sun. This is generally zero, or very small, for inactive objects like asteroids. The model may be expressed as: m = g + 5*log10(D) + 2.5*k*log10(r) where: m = resulting visual magnitude; g = absolute visual magnitude; D = comet-earth distance, in AU; k = luminosity index; and r = comet-sun distance. Note that this model does not take into account the phase angle of sunlight. @OBJXY_HGMAGNITUDE The H/G model also requires two parameters. The first, H, is the magnitude of the object when one AU from the sun and the earth. The other, G, attempts to model the reflection characteristics of a passive surface, such as an asteroid. The model may be expressed with the following code fragment: beta = acos((rp*rp + rho*rho - rsn*rsn)/ (2*rp*rho)); psi_t = exp(log(tan(beta/2.0))*0.63); Psi_1 = exp(-3.33*psi_t); psi_t = exp(log(tan(beta/2.0))*1.22); Psi_2 = exp(-1.87*psi_t); m = H + 5.0*log10(rp*rho) - 2.5*log10((1-G)*Psi_1 + G*Psi_2); where: m = resulting visual magnitude rp = distance from sun to object rho = distance from earth to object rsn = distance from sun to earth Note that this model does not take into account the phase angle of sunlight.